feat: Use @typegpu/gl as a fallback when @typegpu/three is made to generate GLSL - #2794

Pull request overview

This PR updates @typegpu/three to support Three.js’s WebGL backend path by switching TypeGPU shader generation to GLSL via @typegpu/gl when WebGL is detected.

Changes:

• Add @typegpu/gl as a peer dependency and wire it into the workspace lockfile.
• Detect WebGL backend in the node builder and apply glOptions({ shaderStage: 'none' }) to tgpu.resolve(...) calls.
• Adjust function-start detection to handle GLSL-style function declarations.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Reviewed changes

• Declared @typegpu/gl as a peer dependency and wired glOptions({ shaderStage: 'none' }) into the three tgpu.resolve calls when the Three.js builder targets WebGL.
• Added isWebGL() backend detection and findFunctionStart() to handle both WGSL (fn name) and GLSL (type name() function declaration syntax.
• Refactored the dependency-assignment resolution in generate() into a local code variable.
• Updated pnpm-lock.yaml to link the new peer dependency.

ℹ️ Docs will need updating once WebGL works

The @typegpu/three docs currently include a caution block stating that the WebGL fallback does not work. Once this feature branch makes it work, that block and the install instructions should be updated.

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

Reviewed changes

Reviewed the delta that removed the WORKAROUND_wgslToGlslFixups post-processor from @typegpu/gl and replaced it with native GLSL generation.

• Removed WORKAROUND_wgslToGlslFixups from packages/typegpu-gl/src/tgpuRootWebGL.ts and its export in packages/typegpu-gl/src/index.ts.
• Added native array support in packages/typegpu-gl/src/glslGenerator.ts: resolveArraySizeSuffix, array-aware declareGlobalConst, declareGlobalVar, typeAnnotation, typeInstantiation, and _emitVarDecl now emit GLSL type name[N] declarations and type[N](...) constructors.
• Added a numericLiteral override that emits GLSL literals without WGSL f/h suffixes, keeps u for u32, and chooses decimal or exponential form for floats.
• Updated @typegpu/gl test snapshots; all 35 @typegpu/gl tests pass.

⚠️ WebGL fallback remains broken for GLSL signatures

packages/typegpu-three/src/typegpu-node.ts:193 still applies forceExplicitVoidReturn(fnCode) unconditionally. The helper inserts -> void after the first ), which corrupts GLSL function signatures such as float foo() into float foo()-> void. This prevents the WebGL fallback from working even though @typegpu/gl now emits valid GLSL.

# forceExplicitVoidReturn corrupts GLSL signatures

## Affected sites
- packages/typegpu-three/src/typegpu-node.ts:193 — `forceExplicitVoidReturn(fnCode)` is applied to GLSL code

## Required outcome
- GLSL function code must not be passed through the WGSL-specific `forceExplicitVoidReturn` helper.

## Suggested approach
Skip `forceExplicitVoidReturn` when `webgl` is true, or detect whether the resolved code already has a return type in a language-agnostic way.

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

Reviewed changes

Reviewed the delta from the previous pullfrog review head (6b3dea9) to the current head (75504e6). The @typegpu/three changes are byte-for-byte identical to the previous iteration; the new commits come from the upstream feat/make-triangle-work-with-gl-fallback feature branch.

• Eagerly reserved gl_Position and sample in packages/typegpu-gl/src/glslGenerator.ts on the first functionDefinition call, so the shaderStage: 'none' path used by @typegpu/three cannot accidentally use these GLSL keywords as identifiers.
• Updated @typegpu/gl inline snapshots to match improved numeric-literal and zero-constructor emission (1i → 1, 0i → 0, 1.5f → 1.5, vec3() → vec3(0)).
• The @typegpu/three files are unchanged from the previous iteration.

🚨 WebGL fallback still blocked by forceExplicitVoidReturn

packages/typegpu-three/src/typegpu-node.ts:193 still passes the resolved function code through forceExplicitVoidReturn. That helper assumes WGSL syntax: it looks for -> to detect an explicit return type and otherwise appends -> void after the first ). GLSL function declarations do not contain ->, so a signature such as float foo() is corrupted into float foo()-> void, which is invalid GLSL. This was raised in the previous pullfrog review and has not been addressed in this rebase.

# forceExplicitVoidReturn corrupts GLSL signatures

## Affected sites
- packages/typegpu-three/src/typegpu-node.ts:193 — `forceExplicitVoidReturn(fnCode)` is applied to GLSL code

## Required outcome
- GLSL function code must not be passed through the WGSL-specific `forceExplicitVoidReturn` helper.

## Suggested approach
Skip `forceExplicitVoidReturn` when `webgl` is true, or detect whether the resolved code already has a return type in a language-agnostic way.

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

✅ No new issues found.

The prior forceExplicitVoidReturn concern is fixed, and the new GLSL implicit-pointer support is well covered by tests.

Reviewed changes

Reviewed the delta since the prior pullfrog review (75504e6). The latest commits add native GLSL handling for implicit const pointers and fix the WGSL-only return-type helper that was blocking the WebGL fallback.

• Fixed forceExplicitVoidReturn corrupting GLSL signatures. packages/typegpu-three/src/typegpu-node.ts now skips the WGSL-specific helper when the Three.js builder targets WebGL, so GLSL functions no longer get -> void appended.
• Refactored implicit-pointer const emission. packages/typegpu/src/tgsl/wgslGenerator.ts extracted the alias logic into a protected _aliasConstStatement method so language-specific generators can override it.
• Added GLSL implicit-pointer support. packages/typegpu-gl/src/glslGenerator.ts overrides _aliasConstStatement: immutable memory is copied, mutable memory is aliased by inlining the original expression, and runtime index expressions are hoisted into let variables to guarantee single evaluation.
• Added test coverage. packages/typegpu-gl/tests/implicitPointer.test.ts covers immutable copies, mutable aliases, nested member/index accesses, aliases of aliases, and local-variable aliases.

All @typegpu/gl and packages/typegpu tests pass.

  ^{｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

Reviewed changes

Reviewed the delta since the prior pullfrog review (c4ac0890):

• Guarded isWebGL against renderer-less builders. packages/typegpu-three/src/typegpu-node.ts:128 now reads builder.renderer?.backend and returns false when there is no renderer, fixing the open unguarded-deref concern. The new uses the active WebGL builder to infer nested toTSL return types test pins the fix (passes with zero console.warn calls).
• Added a WebGL storage-array test that builds a fake storage node through setup/analyze/generate and asserts GLSL codegen — this test currently fails.
• Added SetupStageData / getSetupStageData plumbing to the builder data so WebGL builders can be exercised through the setup build stage.

⚠️ New WebGL storage-array test fails

packages/typegpu-three/tests/typegpu-node.test.ts:169 asserts the generated compute code contains typegpuReadStorage, but the generator emits plain array indexing instead. Since typegpuReadStorage is defined nowhere in the repo, this test is red on a clean run (verified locally: 4/5 pass, this one fails). Either the storage-array lowering through the typed helper is intended-but-not-implemented (then it needs implementing), or the assertion is stale and should match the real storageValue[2] codegen.

# New WebGL storage-array test fails

## Affected sites
- packages/typegpu-three/tests/typegpu-node.test.ts:169 — expects `typegpuReadStorage` in `builder.getCodes('compute')`
- packages/typegpu-three/tests/typegpu-node.test.ts:153-171 — the failing test itself

## Required outcome
- The test must pass on a clean run. Either implement the typed-helper lowering it describes (or confirm it isn't needed and drop the marker assertion), or fix the expectation to the actual generated code.

## Suggested approach
- Run `pnpm vitest run --project=!browser packages/typegpu-three/tests/typegpu-node.test.ts` to reproduce the failure, then decide whether the feature or the assertion is in error.

ℹ️ Nitpicks

• packages/typegpu-three/src/typegpu-node.ts:84-91 — getSetupStageData/SetupStageData/setupStageDataMap are added but never called anywhere (only getGenerateStageData/getAnalyzeStageData have call sites). If the setup build stage doesn't need its own stage data yet, this is dead code added by the delta.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

Reviewed changes

Reviewed the delta since the prior pullfrog review (0eb9c4fc):

• Deleted both WebGL storage arrays tests. The red typegpuReadStorage test (the prior merge blocker) and the passing uses the active WebGL builder to infer nested toTSL return types test were removed together. The suite is green again (verified locally: typegpu-node.test.ts 3/3, test:types passes), but the throwaway scaffolding they exercised — webglBuilderFor, WebGLStorageArrayNode, THREEWebGLBackendMock, plus the GLSLNodeBuilder and now-unused vi imports — was left behind. The unstable_minify: false lines in typegpu-node.ts are base-branch content, not part of this delta.

⚠️ WebGL fallback path now has zero automated test coverage

Only the red test needed to be removed — its typegpuReadStorage assertion was genuinely wrong, since the generator emits direct GLSL subscripting (storageValue[2]). The passing sibling (uses the active WebGL builder to infer nested toTSL return types) was the only test that drove a TgpuFnNode through a real GLSLNodeBuilder, asserting the isWebGL() + glOptions() + GLSL emission wiring works and that the fromTSL type-inference warning regression stays gone. With it deleted, nothing verifies that a TgpuFnNode actually resolves to GLSL when the builder targets the WebGL backend — the exact feature this PR adds. The remaining three tests only ever exercise the WGSL backend mock.

# WebGL fallback path is untested after test deletion

## Affected sites
- packages/typegpu-three/tests/typegpu-node.test.ts — the deleted `uses the active WebGL builder to infer nested toTSL return types` test (removed in this delta)

## Required outcome
- The `isWebGL` detection, `glOptions()` application, and GLSL `fnDeclaration` emission in `typegpu-node.ts` must have at least one automated assertion, since the PR's whole purpose is making the WebGL/GLSL fallback work.

## Suggested approach
- Keep or restore the passing WebGL-builder test (or an equivalent that builds a `TgpuFnNode` with a WebGL backend and asserts `isWebGL`/`glOptions` behavior), and additionally remove the now-unused test scaffolding.

## Open questions for the human
- The red test also carried a `typegpuReadStorage` intent note ("lowers array reads through a typed TSL helper"). Is the typed-helper storage lowering intended-but-not-implemented, or is direct GLSL subscripting the correct codegen? If the former, that gap should be tracked separately rather than silently dropped with the test.

ℹ️ Nitpicks

• packages/typegpu-three/tests/typegpu-node.test.ts:61-81 — webglBuilderFor, WebGLStorageArrayNode, and THREEWebGLBackendMock are now unreferenced after both WebGL tests were deleted; the import { ... vi } at line 6 is also unused. Leftover scaffolding from the removed tests.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}